---
title: Docker Compose
description: Deploy Tracecat using a Docker Compose template.
icon: docker
---

import DeploymentNote from "/snippets/deployment-note.mdx";
import PublicUrlNote from "/snippets/public-url-note.mdx";
import BasicAuthWarning from "/snippets/basic-auth-warning.mdx";

<DeploymentNote />

<BasicAuthWarning />

## Prerequisites

- [Docker](https://docs.docker.com/engine/install/) version 26.0.0+
- [Docker Compose](https://docs.docker.com/compose/install/) version 2.29.0+
- [openssl](https://www.openssl.org/source/)

## Verify Prerequisites

To verify that Docker Compose and Docker are installed on the machine where you plan to install Tracecat, run the following commands.

```bash
# Check Docker installation
docker

# Check Docker Compose installation
docker compose
```

## Download Configuration Files

<PublicUrlNote />

Tracecat requires a set of environment variables and credentials stored in `.env` file to run.
We created a helpful shell script to generate the `.env` file.
Use the commands listed below to download the required configuration files
(`env.sh`, `.env.example`) and generate your own `.env` file.

```bash
# 1. Download the env.sh installation script
curl -o env.sh https://raw.githubusercontent.com/TracecatHQ/tracecat/0.52.2/env.sh

# 2. Download the .env.example template file (env.sh needs this to generate your .env file)
curl -o .env.example https://raw.githubusercontent.com/TracecatHQ/tracecat/0.52.2/.env.example

# 3. Make the env.sh script executable and run it
chmod +x env.sh && ./env.sh
```

After running `env.sh`, you'll be prompted to input the following:

- Use production mode? - defaults to `y` (use `y` unless you are a Tracecat developer)
- Set `PUBLIC_APP_URL` to - defaults to `localhost`
- Require PostgreSQL SSL mode? - defaults to `n`
- Enter email address for the first user (superadmin) - **required field**

<Info>
  When installing Tracecat on a local workstation, use `localhost` or
  `127.0.0.1` as the IP address. Avoid using `0.0.0.0`, as the frontend will
  attempt to call `0.0.0.0/api/` to access the backend API, causing connection
  issues.
</Info>

<Tip>
  If you want to expose Tracecat on a custom port, you can set `PUBLIC_APP_PORT`
  in the `.env` file. For example, to expose Tracecat UI at
  `http://localhost:8082`, set `PUBLIC_APP_PORT=8082` in the `.env` file.
</Tip>

<Note>
  Setting production mode to `n` changes where Tracecat's remote repository is installed.
  Do not set production mode to `n` unless you are a Tracecat developer.

By default, Tracecat will install the remote repository to the user's home directory at `~/.local/lib/python3.12/site-packages/`.
Setting production mode to `y` will install the remote repository to the `PYTHONUSERBASE` directory specified in enviroment variables.

</Note>

## Download Caddyfile

Tracecat uses Caddy as a reverse proxy.
You'll need to download the following `Caddyfile` to configure this service.

```bash
curl -o Caddyfile https://raw.githubusercontent.com/TracecatHQ/tracecat/0.52.2/Caddyfile
```

## Download Docker Compose File

```bash
curl -o docker-compose.yml https://raw.githubusercontent.com/TracecatHQ/tracecat/0.52.2/docker-compose.yml
```

## Start Tracecat

<Note>
  If you want to expose Tracecat on a custom port (default is `80`), you can set
  `PUBLIC_APP_PORT` in the `.env` file. For example, to expose Tracecat UI at
  `http://localhost:8080`, set `PUBLIC_APP_PORT=8080` in the `.env` file.
</Note>

Run the command below to start Tracecat and all related services.
Make sure your `docker-compose.yml` and generated `.env` files are in the same directory.

```bash
docker compose up
```

Your Tracecat instance should now be running on `http://localhost:${PUBLIC_APP_PORT}`.
To access the Tracecat GUI, visit `http://localhost:${PUBLIC_APP_PORT}`.

![welcome-page](/img/self-hosting/welcome-page.png)

<Tip>
  Tracecat comes with a REST API, you can visit the live API docs at
  `http://localhost:${PUBLIC_APP_PORT}/api/docs`.
</Tip>

## Login

<Note>
  Find out how to configure authentication in Tracecat. [View
  docs](/self-hosting/authentication/overview).
</Note>

For each new Tracecat deployment, the super admin role is assigned to the first user who logs into the Tracecat instance.
This user owns the organization and has admin rights to every workspace in the Tracecat deployment.

**Important:** Only the email address you specified during the `env.sh` setup can become super admin.
You must sign up using exactly that email address to gain super admin privileges.

To proceed, sign up and create an account with a strong and secure password using the super admin email you configured.
Check out the [admin tutorial](/quickstart/admin) for more information.

## Networking

The following env variables are used to configure **external facing** network settings for Tracecat:

- `PUBLIC_APP_URL` - Tracecat frontend URL.
- `PUBLIC_APP_PORT` - Tracecat frontend port.
- `PUBLIC_API_URL` - Tracecat API URL.
- `NEXT_PUBLIC_APP_URL` - Browser client will use this URL to access the Tracecat frontend.
- `NEXT_PUBLIC_API_URL` - Browser client will use this URL to access the Tracecat API.
- `BASE_DOMAIN` - Caddy will use this domain to reverse proxy the Tracecat frontend and API. Defaults to `:{PUBLIC_APP_PORT}`
- `ADDRESS` - Caddy will use this address to bind to the network. Defaults to `0.0.0.0`

Within the docker network, the following env variables are used to configure network settings **within the docker network** for Tracecat:

- `INTERNAL_API_URL` - Tracecat API URL (defaults to `http://api:8000`)
- `INTERNAL_EXECUTOR_URL` - Tracecat executor URL (defaults to `http://executor:8000`)
- `NEXT_SERVER_API_URL` - Tracecat API URL (defaults to `INTERNAL_API_URL`)

## Troubleshooting

### "Network error" / "Failed to fetch" sign-in page

This error occurs when your browser cannot connect to Tracecat API via `PUBLIC_APP_URL`.
Please check the following:

- Do not set `PUBLIC_APP_URL` to `0.0.0.0`. Browsers cannot connect to this address. Use `localhost`, `127.0.0.1`, or your machine's actual IP address instead.
- WSL users: Do not use `127.0.0.1`. Run `ip addr` to find your WSL IP address (usually `172.x.x.x`) and use that instead.
- If you frontend is running on a different machine than the API, set `NEXT_PUBLIC_API_URL` to an address your browser can reach.
- Run `docker compose ps` to verify all services are running.
- Check the temporal service is healthy. Worker connectivity issues can sometimes affect login.
- View container logs: `docker compose logs api` and `docker compose logs temporal`.
- Check firewall and port forwarding if using a reverse proxy.

<Note>
  Related issues: [#1166](https://github.com/TracecatHQ/tracecat/issues/1166),
  [#887](https://github.com/TracecatHQ/tracecat/issues/887),
  [#867](https://github.com/TracecatHQ/tracecat/issues/867),
  [#779](https://github.com/TracecatHQ/tracecat/issues/779)
</Note>

## Next Steps

- Log into Tracecat and build your first playbook. [View quickstart](/quickstart).
- Tracecat comes with basic (email + password) authentication. Find out how to configure other authentication methods. [View docs](/self-hosting/authentication/overview).
- Read inline comments in the generated `.env` file to better understand Tracecat's configurations. [View `.env.example` file](https://github.com/TracecatHQ/tracecat/blob/0.52.2/.env.example).
